package com.example.graphmovieapp.service;

import com.example.graphmovieapp.domain.entity.Person;
import com.example.graphmovieapp.domain.entity.Movie;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.util.List;
import java.util.Optional;

/**
 * PersonService接口，提供人物相关的业务操作
 * 
 * @author GraphMovieApp
 * @version 1.0
 */
public interface PersonService {

    /**
     * 保存人物
     * 
     * @param person 要保存的人物
     * @return 保存后的人物
     */
    Person savePerson(Person person);

    /**
     * 根据ID查找人物
     * 
     * @param id 人物ID
     * @return 匹配的人物，如果不存在则返回Optional.empty()
     */
    Optional<Person> findPersonById(Long id);

    /**
     * 查找所有人物
     * 
     * @return 所有人物列表
     */
    List<Person> findAllPersons();

    /**
     * 根据ID删除人物
     * 
     * @param id 人物ID
     */
    void deletePerson(Long id);

    /**
     * 根据姓名查找人物
     * 
     * @param name 人物姓名
     * @return 匹配的人物，如果不存在则返回Optional.empty()
     */
    Optional<Person> findPersonByName(String name);

    /**
     * 根据出生年份查找人物
     * 
     * @param born 出生年份
     * @return 匹配的人物列表
     */
    List<Person> findPersonsByBorn(Integer born);

    /**
     * 根据姓名模糊查询人物
     * 
     * @param name 姓名关键字
     * @return 包含关键字的人物列表
     */
    List<Person> findPersonsByNameContaining(String name);

    /**
     * 根据姓名模糊查询人物（支持分页）
     * 
     * @param name 姓名关键字
     * @param pageable 分页参数
     * @return 分页的人物列表
     */
    Page<Person> findPersonsByNameContaining(String name, Pageable pageable);

    /**
     * 查找指定演员参演的所有电影
     * 
     * @param name 演员姓名
     * @return 该演员参演的电影列表
     */
    List<Movie> findMoviesActedByPerson(String name);

    /**
     * 查找指定导演执导的所有电影
     * 
     * @param name 导演姓名
     * @return 该导演执导的电影列表
     */
    List<Movie> findMoviesDirectedByPerson(String name);

    /**
     * 查找参演指定电影的演员
     * 
     * @param title 电影标题
     * @return 参演该电影的演员列表
     */
    List<Person> findActorsInMovie(String title);

    /**
     * 查找指定电影的导演
     * 
     * @param title 电影标题
     * @return 该电影的导演列表
     */
    List<Person> findDirectorsOfMovie(String title);

    /**
     * 添加演员到电影
     * 
     * @param personName 演员姓名
     * @param movieTitle 电影标题
     * @return 更新后的人物
     */
    Person addActorToMovie(String personName, String movieTitle);

    /**
     * 添加导演到电影
     * 
     * @param personName 导演姓名
     * @param movieTitle 电影标题
     * @return 更新后的人物
     */
    Person addDirectorToMovie(String personName, String movieTitle);
}